/**
 * LangChain.js 基础API详解
 * 
 * 一、模型调用
 *  1、 LLM 
 *    基础文本生成模型（如 GPT-3.5 ）：
 *    const model = new OpenAI({ temperature: 0.7 }); 
 *    await model.call("你好，介绍react"); 
 *  
 * 2、chatmodel
 *    对话模型（如 GPT-4）：
 *    核心方法：predictMessages()
 *    const chat = new chatOpenAI();
 *    await chat.predictMessage([new HumanMessage("您好!")])
 * 
 * 3、Embedding
 *    文本向量化模型(用于语义检索、聚类)
 *    核心方法：embedQuery() / embedDocument()
 *    const embedings = new OpenAIEmbeddings()
 *    const vec = await embedding.embedQuery("react技术")
 *    
 *    关键参数说明：
 *    * temperature(0-2): 控制生成随机性，值得越高,结果越多样性
 *    * maxTokens：限制生成文本的最大长度
 *    * streaming: 启用流式传输(适合实时聊天场景)
 * 
 * 
 * 二、提示词模板(Prompts)
 *  1、基础模版
 *    import { PromptTemplate } from "@langchain/core/prompts"
 *    
 *    // 单变量模板
 *    const template = "用{style}风格翻译以下文本：{text}" ;
 *    const prompt = new PromptTempalte({
 *       template,
 *       inputVariables: ["style", "text"],
 *    });
 * 
 * 
 *  2、使用示例
 *    const formattedPrompt = await prompt.format({
 *        style:"文言文",
 *        text: "Hello world",
 *     });
 *     // 输出："用文言文风格翻译以下文本：Hello world"
 * 
 * 
 *  3、Few-shot模板
 *    嵌入示例提升模型表现
 * 
 *    import { FewShotPromptTemplate } from"langchain/prompts";
 *    
 *    const examples = [
 *       { input: "高兴", output: "欣喜若狂" },
 *       { input: "悲伤", output: "心如刀绞" }
 *    ];
 * 
 *    const examplePrompt = new PromptTemplate({
 *       template: "输入：{input}\n输出：{output}",
 *       inputVariables: ["input", "output"],
 *    });
 * 
 *    const fewShotPrompt = new FewShotPromptTemplate({
 *        examples,
 *        examplePrompt,
 *        suffix: "输入：{adjective}\n输出：", 
 *        inputVariables: ["adjective"],
 *    });
 *    
 *    await fewShotPrompt.format({ adjective: "愤怒" });
 * 
 *    /* 输出：
 *       输入：高兴
 *       输出：欣喜若狂
 * 
 *       输入：悲伤
 *       输出：心如刀绞
 * 
 *       输入：愤怒
 *       输出： 
 * 
 * 
 *  4、文件模板加载
 *     从外部文件读取模板：
 *     import fs from "fs";
 *     import { PromptTemplate } from "@langchain/core/prompts"
 *     
 *     const template = fs.readFileSync("./prompts/email_template.txt", "utf-8")
 *     const prompt = new PromptTempate({
 *        template,
 *        inputVariables:["userName","product"],
 *     });
 * 
 * 
 * 三、链式调用(Chains)-(langchain核心)
 *    通过组合多个组件构建复杂工作流，是 langchain 核心模块：
 *    1、LLMChain(基础链)
 *       const chain = new LLMChain({
 *          llm: new OpenAI(),
 *          prompt: new PromptTemplate({
 *             template: "生成关于{topic}的{num}条冷知识",
 *             inputVariables: ["topic","num"]
 *           }),
 *        });
 *       
 *       const res = await chain.call({ topic: "react", num:3});
 *       // 输出：模型生成3条react的冷知识
 * 
 *    2、SequentialChain（顺序链）
 *      串联多个链实现分步处理：
 *      import { SequentialChain } from "langchain/chains";
 * 
 *      const chain1 = new LLMChain({ ... }); // 生成文章大纲
 *      const chain2 = new LLMChain({ ... }); // 扩展章节内容
 *      const chain3 = new LLMChain({ ... }); // 优化语言风格
 * 
 *      const overallChain = new SequentialChain({
 *          chains: [chain1, chain2, chain3],
 *          inputVariables: ["title"],
 *          outputVariables: ["outline", "content", "final"],
 *      });
 *      
 *      const result = await overallChain.call({title:"前端已死，还有未来"})
 * 
 *    3、TransformChain（转换链）
 *       自定义数据处理逻辑：
 *       import { TransformChain } from "langchain/chains";
 * 
 *       const transform = new Transforchain({
 *           transform: async (input) => {
 *               // 自定义处理逻辑(如文本清晰)
 *               return { cleaned: inputs.text.replace(/\d+/g,"")};
 *           },
 *           inputVariables: ["text"],
 *           outputVariables: ["cleaned"],
 *       });
 * 
 * 
 * 四、文档加载器(Document Loaders)
 *    支持从多种来源加载结构化文档，可以用来RAG的知识库录入：
 *    1、本地文件：加载 文本/PDF/Word 文档。
 *      const loader = new TextLoader("example.txt");
 *      const docs = await loader.load();
 * 
 *      const loader2 = new PDFLoader("report.pdf");
 *      const docs2 = await loader2.load();
 * 
 *      console.log({ docs })
 *      console.log({ docs2 })
 * 
 *    2、网页内容：抓取指定URL的HTML内容
 *       const loader = new CheerioWebBaseLoader("https://exampleurl.com")
 *       const docs = await loader.load();
 *       console.log({ docs });
 * 
 *    3、数据库：从 MySql/MongoDB 读取数据
 *      import { createClient } from"@supabase/supabase-js";
 *      import { OpenAIEmbeddings } from"@langchain/openai";
 *      import { SupabaseHybridSearch } from"@langchain/community/retrievers/supabase";
 * 
 *      // 初始化 Supabase 客户端
 *      const client = createClient(
 *          process.env.SUPABASE_URL,
 *          process.env.SUPABASE_PRIVATE_KEY,
 *      );
 * 
 *    // 创建混合检查器
 *       const retriever = new SupabaseHybridSearch(new OpenAIEmbeddings(), {
 *          client,
 *          similarityK:5,   // 语义搜索返回结果数
 *          keywordK: 3,           // 关键词搜索返回结果数
 *          tableName: "documents", // 数据库表名
 *          similarityQueryName: "match_documents", // 语义搜索函数名
 *          keywordQueryName: "kw_match_documents", // 关键词搜索函数名
 *          // 高级参数
 *          reRanker:(result) => {
 *            // 自定义结果合并策略（如：加权分数）
 *            return results.sort((a,b) => b.score - a.score)
 *          }
 *        })
 * 
 *    4、云存储：从 AWS S3/GCS 加载文件。
 *       const loader = new S3Loader({
 *          bucket:"my-document-bucket-123",
 *          key:"AccountingOverview.pdf",
 *          s3Config: {
 *              region: "us-east-1",
 *              credentials: {
 *                  accessKeyId: "<YourAccessKeyId>",
 *                  secretAccessKey: "<YourSecretAccessKey>",
 *              },
 *          },
 *          unstructuredAPIURL:"<YourUnstructuredAPIURL>",
 *          unstructuredAPIKey: "<YourUnstructuredAPIKey>",
 *       });
 *       const docs = await loader.load();
 * 
 *     5、文档分块处理
 *        可以用来做 embeddings 
 *        import { RecursiveCharacterTextSplitter } from "langchain/text_splitter";
 *         
 *        const splitter = new RecursiveCharacterTextSplitter({
 *           chunkSize: 500,    // 单块最大字符数
 *           chunkOverlap: 50,  // 块间重叠字符
 *        });
 * 
 *        const docs = await loader.load();
 *        const splitDocs = await splitter.splitDocuments(docs);
 * 
 * 
 * 五、上下文管理器(Memory)
 *    管理对话或任务的上下文状态:
 *    1、对话记忆
 *      import { BufferMemory } from "langchain/memory";
 *      
 *      const memory = new BufferMemory({
 *          memorykey: "chat_history",  // 存储对话的历史字段名
 *      });
 *      
 *      const chain = new ConversationCHain({
 *          llm:new chatopenAI(),
 *          memory
 *      });
 * 
 *      // 连接对话
 *      await chain.call({ input: "您好!"});
 *      await chain.call({ input: "刚才我们聊了什么呢？"})
 * 
 *    2、实体记忆
 *       跟踪待定实体信息
 *       import { EntityMemory } from "langchain/memory"
 * 
 *       const memory = new EntityMemory({
 *          llm: new OpenAI(),
 *          entities: ["username","preferences"],  // 需要跟踪的实体
 *       })；
 *       
 *      await memory.saveContext(
 *          {input: "我叫小明,喜欢研究 react 技术"}，
 *          {output: "已记录您的偏好"}
 *      );
 *      
 *      const currentEntities = await memory.loadEntities();
 *      // 输出: { userName: "小明", preferences: "react技术" }
 * 
 * 
 * 六、输出解析(Output Parsers)
 *    将模型返回的文本转换为结构化数据，实用功能：
 *    1、基础解析器
 *      import { StringOutputParser } from "@langchain/core/output_parsers";
 *      
 *      const chain = prompt.pipe(model).pipe(new StringOutputParser());
 *      const result = await chain.invoke({ topic: "react技术" });
 *      // result "React技术是一个用于构建用户界面的JavaScript库，其核心用途包括：1) 组件化开发，2) 虚拟DOM高效更新，3) 支持单页应用(SPA)开发。"
 * 
 *    2、结构化解析，json
 *      import { StructuredOutputParser } from"langchain/output_parsers";
 * 
 *      // 定义输出Schema
 *      const parser = StructuredOutputParser.fromZodSchema(
 *          z.object({
 *              title: z.string.describe("生成的文章标题"),
 *              keywords: z.array(z.string()).describe("3-5个关键词"),
 *              content: z.string().describe("不少于500字的内容")
 *          })
 *      );
 * 
 *      const chain = new LLMChain({
 *         llm: model,
 *         prompt: new PromptTemplate({
 *            template: "根据主题{topic}写一篇文章\n{format_instructions}",
 *            inputVariables: ["topic"],
 *            partialVariables: { format_instructions: parser.getFormatInstructions() }
 *         });,
 *          outputParser: parser
 *      });
 *      
 *      const res = await chain.call({ topic: "react技术" });
 * 
 *      {
 *          title: "React技术：现代前端开发的核心理念",
 *          keywords: ["组件化", "虚拟DOM", "Hooks", "SPA", "状态管理"],
 *          content: "React是由Facebook开发的一个用于构建用户界面的JavaScript库...（至少500字）"
 *       }
 *
 * 
 * 七、工具与代理（Tools & Agents）
 *    集成外部API扩展模型能力：
 *    1、预定义工具
 *      使用langchain内置的工具：
 *      import { Calculator, SerpAPI } from "langchain/tools";
 * 
 *      const tools = [
 *          new Calculator,  // 数学计算
 *          new SerpAPI(),   // 实时网络搜索
 *          new WolframAlphaTool(),  // 科学计算
 *      ];
 * 
 *    2、自定义工具
 *      自定义开发工具
 *      import { DynamicTool } from "langchain/tools";
 * 
 *      export const weatherTool = new DynamicTool({
 *         name: "get_weather",
 *         description: "查询指定城市的天气",
 *         func: async (city) => {
 *              const apiUrl = `https://api.weather.com/${city}`;
 *              return await fetch(apiUrl).then(res => res.json());
 *         }
 *      });
 *       
 *      代理执行：
 *      import { initializeAgentExecutorWithOptions } from "langchain/agents";
 *      import { weatherTool } from 'weatherTool
 * 
 *      const executor = await initializeAgentExecutorWithOptions(
 *          tools:[weatherTool],
 *          new ChatOpenAI({ temperature: 0 }), 
 *          { agentType: "structured-chat-zero-shot-react-description" } 
 *      );
 * 
 *      const res = await executor.invoke({
 *          input: "上海当前温度是多少？比纽约高多少摄氏度？"
 *      })
 *       
 *      // 模型将自动调用天气查询工具和计算器
 *      structured-chat-zero-shot-react-description是 LangChain 框架中一种结构化对话代理（Structured Chat Agent） 的类型，
 *      专为让大模型（如 GPT-4）无需示例学习（Zero-Shot） 即可调用外部工具链而设计。
 *  
 * 
 * 
 * 八、检索增强(Retrieval) RAG
 *     结合向量数据库实现知识增强：
 *     import { MemoryVectorStore } from"langchain/vectorstores/memory";
 *     import { OpenAIEmbeddings } from"@langchain/openai";
 * 
 *     // 1、 加载文档并向量化
 *     const vectorStore = await MemoryVectorStore.fromDocuments(
 *         splitDocs,
 *         new OpenAIEmbeddings()
 *     );
 * 
 *     // 2、语义检索
 *     const results = await vectorStore.similaritySearch("神经网络的发展历史", 3);
 * 
 *     // 3、将解锁结果注入提示词
 *     const chain = createRetrievalChain({
 *          retriever: vectorStore.asRetriever(),
 *          combineDocsChain: new LLMChain(...)
 *     })
*/

 

  




